.TH stoker_ldap 5 "17 September 2008" "version 0.91" "Stoker Manual"
.SH NAME
stoker_ldap \- Stoker LDAP machine source
.SH DESCRIPTION
Stoker can utilize an LDAP (Lightweight Directory Access Protocol) server as
a source for machine and group definitions.
LDAP provides a mechanism by which a cluster of systems can be made scalable,
since machine information can be stored in one place and used as a source for
Stoker, DNS servers, DHCP servers, and other useful network utilities.
To use LDAP, the host running stoker(8) must have the python-ldap package
(http://python-ldap.sourceforge.net) installed.
This package is only a
dependency of Stoker if LDAP is enabled in stoker.conf(5).
.SH LDAP SERVER REQUIREMENTS
A working LDAP server, such as slapd(8) from OpenLDAP, must be available and
reachable from the host that will run Stoker.
Within the server tree, a set of objects conforming to RFC 2307 (NIS schema)
must be present.
These objects (of the ipHost objectClass) \fBMUST\fR be in a hierarchy such
that every ipHost object is a child either of the base DN directly, or of
OrganizationalUnits (ou's) that descend directly from the base DN.
Due to a limitation in the software, there must be no object of any type other
than OrganizationalUnit between any ipHost and the base DN.
.PP
For a machine to be used with Wake-On-Lan, its ipHost object MUST also have
both a \fBdevice\fR objectClass and an \fBieee802Device\fR, and the
\fBmacAddress\fR field MUST be set to the MAC address of the machine.
.SH CONFIGURATION DIRECTIVES
The following stoker.conf(5) directives configure Stoker to use an LDAP server
as a machine source:
.TP
.B use_ldap = <true | false>
Enables or disables the LDAP machine source.
.TP
.B ldap_uri = <uri>
Specifies the URI of the LDAP server to use (ldap:// or ldaps://).
.TP
.B ldap_use_tls = <true | false>
Enables or disables use of the LDAP STARTTLS operation.
See ldap.conf(5) for more information about TLS.
.TP
.B ldap_base_dn = <dn>
Specifies the Distinguished Name of the root element (typically an ou) of
the LDAP subtree to be searched for machine definitions.
.TP
.B ldap_filter = <filter_expression>
Use a custom LDAP query filter expression to identify hosts.
If unspecified, the default (objectClass=ipHost) filter will be used.
See ldapsearch(1) and ldap_search(3) for details on filter syntax.
.TP
.B ldap_bind_dn = <dn>
Bind to the LDAP server with a specific DN.
If omitted, unset, or set to an empty string, then an anonymous bind will be
used.
.TP
.B ldap_bind_pw = <credential>
Credential to use with
.B ldap_bind_dn
when binding to the LDAP server non-anonymously.
.SH MACHINE GROUPS
Stoker groups are derived from the hierarchy of ou's under the base DN.
Consider the following hierarchy, with the base DN set to
ou=DHCP,ou=Hosts,dc=localhost:
.PP
.nf
dc=localhost
  ou=Hosts
    ou=DHCP
    	ou=foobar
	     ou=foo
	       cn=Machine1,ou=foo,ou=foobar,ou=DHCP,ou=Hosts,dc=localhost
	       cn=Machine2,ou=foo,ou=foobar,ou=DHCP,ou=Hosts,dc=localhost
   	  ou=bar
   	    cn=Machine3,ou=bar,ou=foobar,ou=DHCP,ou=Hosts,dc=localhost
.fi
.PP
The following groups will be available to Stoker:
.TP
.B foo
Resolves to Machine1 and Machine2
.TP
.B bar
Resolves to Machine 3
.TP
.B foobar
Resolves to Machine 1, Machine 2, and Machine 3
.SH STANDARDS
With the exception of the restriction on objects other than OrganizationalUnits
between ipHost objects and the base DN, Stoker conforms to RFC 2307
("An Approach for Using LDAP as a Network Information Service").
.SH EXAMPLES
A simple set of configuration directives to connect to an LDAP server on the
same host as Stoker, without TLS, using an anonymous bind:

.nf
use_ldap = true
ldap_uri = ldap://127.0.0.1
ldap_base_dn = ou=DHCP,ou=Hosts,dc=localhost
.fi

Configure Stoker to connect to server example.none using TLS with SASL
authentication to port 886.
Bind to the server with the Manager account,
using the default password "secret".
Also try to use objects that are
different than, but compatible with, ipHost objects (this may not work
in practice!):

.nf
use_ldap = true
ldap_uri = ldaps://example.none:886
ldap_use_tls = true
ldap_base_dn = ou=DHCP,ou=Hosts,dc=example,dc=none
ldap_bind_dn = cn=Manager,dc=example,dc=none
ldap_bind_pw = secret
ldap_filter = (objectClass=myMagicIpHost)
.fi
.SH SEE ALSO
stoker.conf(5), scf2(5), stoker(8), slapd(8), ldap(3), ldapsearch(1),
ldap_search(3), ldap.conf(5)

RFC 2307 <http://www.ietf.org/rfc/rfc2307.txt>
.SH AUTHOR
Mike Murphy <mamurph@cs.clemson.edu>
.SH DISCLAIMER
This material is based upon work supported under a National Science
Foundation Graduate Research Fellowship.
Any opinions, findings, conclusions or recommendations expressed in this
publication are those of the author(s) and do not necessarily reflect the
views of the National Science Foundation.
